btleplug

btleplug is an async Rust BLE library, supporting Windows 10, macOS, Linux, and possibly iOS and Android. It grew out of several earlier abandoned libraries for various platforms (rumble, blurmac, etc...), with the goal of building a fully cross platform library. Adding support for other platforms such as Android is also planned.

btleplug is meant to be host/central mode only. If you are interested in peripheral BTLE (i.e. acting like a Bluetooth LE device instead of connecting to one), check out bluster.

This library DOES NOT SUPPORT BLUETOOTH 2/CLASSIC. There are no plans to add BT2/Classic support.

v0.8+, now with Async!

Note that as of v0.8, btleplug is now async, using tokio as a runtime. The API has changed drastically since 0.7, and no longer resembles rumble as much as it did before.

While we've done our best to test it, we expect there will be issues with this release. Please file issues as you find them and we will address them as soon as possible.

Development Goals

The issues in this repo reflect the development goals of the project. First and foremost is getting as many platforms as possible up and running enough to support our main usage of this library.

Beyond that, some of our other goals are:

• Add Android (now happening in v0.9)
• Add FFI so this library can be used from C (and maybe C++ using cxx.
• Possibly create a WASM compatible layer using wasm-bindgen and WebBluetooth.

Platform Status

• Linux / Windows / macOS
  • Device enumeration and characteristic/services implemented, works ok.
  • Please file bugs and missing features if you find them.
• iOS
  • Trying to figure out if the macOS implementation will translate, minus things having to do with background processing. Might just work already?
  • Tracking issue here
  • Please file bugs and missing features if you find them.
• Android
  • Android implementation is in testing now, should be released soon (probably as 0.9).
  • Tracking issue here.
  • Please hold off on filing more issues until base implementation is landed.
• WASM/WebBluetooth
  • WebBluetooth has been added to wasm-bindgen's web-sys by @qdot, and a full implementation has been done in other libraries that could easily be ported here. This is now definitely in the works, once the new API surface is solidified.
  • Tracking issue here
  • Please hold off on filing more issues until base implementation is landed.

Linux Device Discovery Cavaet

Note that using Event Based Discovery on Bluez (Linux) can cause very odd issues with service discovery, timeouts, and general weirdness. See Issue 165 for more info, but for now it's recommended to use polling on linux (as seen in the subscribe_notify_characteristic example) instead of event driven device discovery (as seen in the event_driven_discovery example).

macOS permissions note

To use Bluetooth on macOS Big Sur (11) or later, you need to either package your binary into an application bundle with an Info.plist including NSBluetoothAlwaysUsageDescription, or (for a command-line application such as the examples included with btleplug) enable the Bluetooth permission for your terminal. You can do the latter by going to System Preferences → Security & Privacy → Privacy → Bluetooth, clicking the '+' button, and selecting 'Terminal' (or iTerm or whichever terminal applicatation you use).

Platform Feature Table

• X: Completed and released
• O: In development
• Blank: Not started

Library Features

Serialization/Deserialization

To enable implementation of serde's Serialize and Deserialize across some common types in the api module, use the serde feature.

[dependencies]
btleplug = { version = "0.4", features = ["serde"] }

License

BTLEPlug is covered under a BSD 3-Clause License, with some parts from Rumble/Blurmac covered under MIT/Apache dual license, and BSD 3-Clause licenses, respectively. See LICENSE.md for more info and copyright information.